feat(skill): split architecture-documentation contract into vocabulary + arc42-authoring skill#577
Draft
JensGrote wants to merge 1 commit into
Conversation
Extract procedural content from the over-grown architecture-documentation contract (2922 chars) into a new arc42-authoring skill. Absorb crosscutting-concepts contract into the skill as chapter-8-baseline.md. Shrink architecture-documentation contract to vocabulary only (~385 chars). Closes LLM-Coding#529
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yml Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
refactor(contract): split architecture-documentation into vocabulary contract + arc42-authoring skill
(German version below)
Splits the over-grown
architecture-documentationcontract (2922 chars) into:arc42-authoring/— carries the how-toCloses #529. Absorbs
crosscutting-conceptsinto the skill.Assessment against project taxonomy
Contract/Skill boundary — catalog evidence
templatefield incontracts.jsonSKILL.md+references/+prompts/architecture-documentation)arc42-authoring)Size analysis — the outlier
architecture-documentationsocratic-code-theory-recoveryexplaining-teachingtdd-hamburg-stylearchitecture-documentationis the only contract >1200 chars that has no companion skill.socratic-code-theory-recoveryis similarly long but justified as a condensed reminder of its companion skill — the procedural depth lives in the skill, not the contract alone.Precedent: "invoke a skill for depth" pattern
The
explaining-teachingcontract (#573) proves this pattern works:socratic-code-theory-recoveryskillConsistency with Harness Inventory
The Harness Inventory page (
docs/harness-inventory.adoc) separates "what a layer checks" (definition) from "how to deploy it" (procedure). Same lens: contract = the what, skill = the how.Changes
1. New skill:
skill/arc42-authoring/Content extracted 1:1 from the current
architecture-documentationandcrosscutting-conceptscontracts. No information lost — only relocated.2. Shrunken contract:
architecture-documentationFrom 2922 chars → ~340 chars:
3. Absorbed:
crosscutting-conceptsMoved to
skill/arc42-authoring/references/chapter-8-baseline.md. The contract entry is removed fromcontracts.json.4. Socratic overlap resolution
The
socratic-code-theory-recoveryskill'sreferences/arc42.mdcontains a Phase 1 decomposition guide (Q-IDs, when to stop decomposing) — this is specific to the Socratic workflow, not to arc42 authoring. No overlap — both skills coexist without duplication:arc42-authoringsocratic-code-theory-recoveryTradeoff acknowledged
The traceability rules move from always-on to on-demand. For architecture work the skill is invoked anyway — no loss. For someone only reading the contract as a reminder, the detail was already too large for always-on context — this is a correction, not a regression (as #529 states).
Deutsche Version
refactor(contract): architecture-documentation in Vokabular-Contract + arc42-authoring-Skill aufteilen
Teilt den überwachsenen
architecture-documentation-Contract (2922 Zeichen) auf in:arc42-authoring/— enthält das WieSchließt #529. Absorbiert
crosscutting-conceptsin den Skill.Bewertung gegen die Projekt-Taxonomie
Contract/Skill-Grenze — Katalog-Evidenz
template-Feld incontracts.jsonSKILL.md+references/+prompts/architecture-documentation)arc42-authoring)Größenanalyse — der Ausreißer
architecture-documentationsocratic-code-theory-recoveryexplaining-teachingtdd-hamburg-stylearchitecture-documentationist der einzige Contract >1200 Zeichen ohne Begleit-Skill.socratic-code-theory-recoveryist ähnlich lang, aber gerechtfertigt als kondensierte Erinnerung seines Begleit-Skills — die prozedurale Tiefe lebt im Skill, nicht allein im Contract.Präzedenzfall: „invoke a skill for depth"-Pattern
Der
explaining-teaching-Contract (#573) beweist, dass dieses Pattern funktioniert:socratic-code-theory-recovery-SkillKonsistenz mit der Harness Inventory
Die Harness-Inventory-Seite (
docs/harness-inventory.adoc) trennt „was eine Schicht prüft" (Definition) von „wie man sie deployt" (Prozedur). Gleiche Linse: Contract = das Was, Skill = das Wie.Änderungen
1. Neuer Skill:
skill/arc42-authoring/Inhalt 1:1 extrahiert aus den aktuellen Contracts
architecture-documentationundcrosscutting-concepts. Keine Information geht verloren — nur umgezogen.2. Eingedampfter Contract:
architecture-documentationVon 2922 Zeichen → ~340 Zeichen:
3. Absorbiert:
crosscutting-conceptsVerschoben nach
skill/arc42-authoring/references/chapter-8-baseline.md. Der Contract-Eintrag wird auscontracts.jsonentfernt.4. Socratic-Überschneidung aufgelöst
Die
references/arc42.mddessocratic-code-theory-recovery-Skills enthält einen Phase-1-Dekompositions-Guide (Q-IDs, wann man aufhört zu dekomponieren) — das ist spezifisch für den Socratic-Workflow, nicht für arc42-Authoring. Keine Überschneidung — beide Skills koexistieren ohne Duplikation:arc42-authoringsocratic-code-theory-recoveryTrade-off anerkannt
Die Traceability-Regeln wandern von always-on zu on-demand. Für Architekturarbeit wird der Skill ohnehin aufgerufen — kein Verlust. Für jemanden, der den Contract nur als Erinnerung liest, war das Detail bereits zu umfangreich für always-on-Kontext — dies ist eine Korrektur, keine Regression (wie #529 feststellt).